home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 151-175 / disk_152 / blk / bdoc < prev    next >
Text File  |  1992-05-06  |  10KB  |  254 lines
  1.  
  2.  
  3.           BLK - Automatic Requester Generator
  4.  
  5.  
  6. BLK generates C code for declaring requesters.  It automatically formats
  7. borders and text and generates the declarations for them.  The requester
  8. can contain boolean, string and proportional gadgets.
  9.  
  10.  
  11. Boxes:
  12.  
  13. BLK formats requesters as nested boxes.  The root box is the requester
  14. itself.  Inner boxes can be formatted horizontally or vertically.  Borders
  15. and text strings are thought of as boxes for the purpose of formatting.  The
  16. box grammer, which is loosly based on lisp syntax, can be described by the
  17. BNF description given below.  Non-terminal symbols are named and terminal
  18. symbols are double quoted strings.
  19.  
  20.    box   :== fill | text | bord | block | seq
  21.    fill  :== "f"
  22.    text  :== "(t" onum str ")"
  23.    str   :== [double quoted string]
  24.    bord  :== rule | "(" rule num onum ")"
  25.    rule  :== "|" | "-"
  26.    block :== "(b" num num ")"
  27.    seq   :== "(" ("h"|"v") blist ")"
  28.    blist :== box | box blist
  29.    onum  :== num | [nothing]
  30.    num   :== [unsigned integer]
  31.  
  32. Some examples:
  33.  
  34. The following produces a 10 x 10 pixel square:
  35.  
  36.    (h | (v - (b 10 10) - ) | )
  37.  
  38. The central structure, "(b 10 10)," is a 10 x 10 block.  This is one of three
  39. boxes in a vbox, or vertically oriented list of boxes.  The other two boxes
  40. in the list are hrules, "-," which are horizontal "rules," or lines.  This
  41. produces a box containing an empty area with lines above and below it.  This
  42. box is further included with two vertical rules, "|," in an hbox - a
  43. horizontally oriented list.  This puts horizontal lines on each side of the
  44. box, closing the square.
  45.  
  46.       -----       |-----|
  47.       xxxxx       |xxxxx|
  48.       xxxxx       |xxxxx|
  49.       xxxxx       |xxxxx|
  50.       -----       |-----|
  51.  
  52. Rules are elastic, and while they have no intrinsic length they will expand
  53. to fill any space available within their bounding box.  The vbox,
  54. "(v - (b 10 10) - )," has dimensions 10 x 12, so each hrule expands to a
  55. length of 10.
  56.  
  57. Fills are another type of elastic object.  For example, suppose you wanted
  58. to format a set of strings, like:
  59.  
  60.       Line #1
  61.       Blah Blah
  62.       ETC
  63.  
  64. You could list the text boxes in a vbox, thus:
  65.  
  66.    (v (t"Line #1") (t"Blah Blah") (t"ETC"))
  67.  
  68. This would produce the formated lines as above.  But then suppose you wanted
  69. each line centered within its box.  For this you use fills.  Each fill
  70. expands to take up as much free space as it can within its bounding box, and
  71. if a string is sandwiched between two fills horizontally, it will be
  72. squeezed by competing fills into the center of its bounding box.
  73.  
  74.    (v
  75.       (h f (t"Line #1")   f)
  76.       (h f (t"Blah Blah") f)
  77.       (h f (t"ETC")       f)
  78.     )
  79.  
  80. Now the boxes within the vbox are not text boxes but hboxes containing text
  81. boxes with fills to the left and right.  The width of the vbox is computed
  82. as the maximum width of each box it contains.  Since fills have no intrinsic
  83. size, the widest hbox is the one containing the text box (t"Blah Blah"),
  84. which has a width of 9 characters, or 72 pixels.  (BLK always assumes an
  85. 8x8 font.)  So each of the other two shorter hboxes are contained
  86. within a vbox of width 72, so each fill expands to make up the difference.
  87. For example, the first hbox contains two fills and a 56 pixel wide text box.
  88. To fill up a 72 pixel wide bounding box, each fill can expand 8 pixels
  89. horizontally, thus centering the text box inbetween them.  The result is:
  90.  
  91.       Line #1
  92.      Blah Blah
  93.         ETC
  94.  
  95. This whole structure is just a box, and can be used within other box
  96. structures.  For example, to put a border around the above box, you could
  97. use the definition from the first example.  Specifically:
  98.  
  99.  (h | (v - 
  100.    (v
  101.       (h f (t"Line #1")   f)
  102.       (h f (t"Blah Blah") f)
  103.       (h f (t"ETC")       f)
  104.     )
  105.   -) |)
  106.  
  107. The problem with this (you will see if you try it) is that the rules
  108. surrounds the text too closely.  Since there is no space between the text and
  109. the lines they lie almost right on top of each other.  Text boxes look ok
  110. right next to each other, but rules need to be explicitly spaced away from
  111. text.  This can be done with "struts," blocks used explicitly as spacers,
  112. like so:
  113.  
  114.  (h | (v - (b 0 5) (h (b 5 0)
  115.    (v
  116.       (h f (t"Line #1")   f)
  117.       (h f (t"Blah Blah") f)
  118.       (h f (t"ETC")       f)
  119.     )
  120.   (b 5 0)) (b 0 5) -) |)
  121.  
  122. The 0 x 5 and 5 x 0 blocks have no volume but since they have width or
  123. height, they affect the spacing of the other components in their h- or
  124. vboxes.
  125.  
  126. Text and rules take on the default color (see "BLK files" below) unless the
  127. color is explicitly stated.  For text boxes this is done with the optional
  128. parameter in the text box description, as in (t 3 "hi there"), which
  129. specifies that the text be color #3.  For rules, a different description
  130. format is used.  Instead of simply | or -, a form such as (| 1 3) or (- 1 2)
  131. is used.  The two examples create a vrule of color 3 and an hrule of color 2
  132. respectively.  The first number is the width of the rule and should always
  133. be 1.
  134.  
  135. This is about all there is to it.  With these simple tools, it is possible
  136. to design a wide variety of nicely layed-out requesters without dealing with
  137. a single number or C struct.  What is more, the strings in the above box
  138. definition could be changed to anything, and the result would still be three
  139. strings centered within a perfectly sized box.
  140.  
  141.  
  142. Gadgets:
  143.  
  144. Any sub-box in a box definition can be defined to be a gadget hit box by
  145. following it with the sequence:
  146.  
  147.    ":" num
  148.  
  149. From the above example, each text box could be defined as a hit box for a
  150. gadget by restating it as:
  151.  
  152.       (h f (t"Line #1"):1   f)
  153.       (h f (t"Blah Blah"):2 f)
  154.       (h f (t"ETC"):3       f)
  155.  
  156. Given these box definitions, BLK will generate code for 3 BOOLEAN,
  157. RELVERIFY, REQGADGET, GADGHCOMP gadgets with the GadgetID's 1,2 and 3.
  158. Other types of gadgets can be defined using an extended gadget definition.
  159. These are of the form:
  160.  
  161.    num {"s"|"p"} {":"id} flags
  162.  
  163. Stuff in {}'s is optional; "id" and "flags" are double-quoted strings.
  164. "Num" is the id number for the gadget given after the ":" in the box
  165. definition.  The optional "s" or "p" specify string or proportional gadgets,
  166. the default being boolean.  The optional "id" string specifies a string to
  167. be used for the GadgetID field in the gadget struct instead of just using
  168. "0x<num>," where num is the id given in the box description.  "Flags" is a
  169. set of characters used to specify flags available in defining a gadget.
  170. Valid flags are (case is significant):
  171.  
  172.       B : GADGHBOX  (default is GADGHCOMP if this is ommited)
  173.       t : TOGGLESELECT
  174.       v : RELVERIFY
  175.       e : ENDGADGET
  176.       i : GADGIMMEDIATE
  177.       c : STRINGCENTER  (string gadgets only)
  178.       f : FOLLOWMOUSE
  179.  
  180. The default flags string is "v".  Here are some examples:
  181.  
  182. 1p""              - proportional gadget with no flags
  183. 7:"OK_ID""ev"     - boolean gadget with id "OK_ID"
  184.                      RELVERIFY and ENDGADGET flags set
  185. 5s"v"             - RELVERIFY string gadget
  186. 5s:"STR_ID""i"    - string gadget with id "STR_ID", GADGIMMEDIATE flag
  187.  
  188.  
  189. BLK output:
  190.  
  191. The code that BLK outputs follows some simple conventions.  These were
  192. implemented for my own convenience and can be changed by altering the source
  193. code.  Structs are assigned in arrays, the name of each array being some
  194. base name followed by the type of struct.  For example, if the base name
  195. were xyz, some structs would be xyz_req, xyz_str, etc.  They are:
  196.  
  197.    struct Requester <base>_req      /* not an array */
  198.  
  199.    struct Gadget <base>_gad[]       /* always included */
  200.    struct IntuiText <base>_txt[]
  201.    struct Border <base>_brd[]
  202.    short <base>_brd_XY[]
  203.  
  204.    UBYTE <base>_nbuf[][NUMCHR]      /* only if string gadgets defined */
  205.    struct StringInfo <base>_sinfo[]
  206.  
  207.    struct Image <base>_pimg[]       /* only if prop gadgets defined */
  208.    struct PropInfo <base>_pinfo[]
  209.  
  210. In user code, the symbol "ta" must be declared as struct TextAttr as in:
  211.  
  212.    struct TextAttr ta = { ... };  /* or */
  213.    extern struct TextAttr ta;
  214.  
  215. To use string gadgets, the symbol "NUMCHR" must be #defined as the number of
  216. characters in the string buffer.  The symbol "undo" must be declared as
  217.  
  218.    UBYTE undo[NUMCHR];
  219.  
  220. to be used as the undo buffer for string gadgets.  The string buffers will
  221. be assigned in the order that they are encountered in reading the box
  222. description, so the buffer for the first encountered will be <base>_nbuf[0],
  223. the buffer for the second will be <base>_nbuf[1], and so on.
  224.  
  225.  
  226. BLK files:
  227.  
  228. A blk input file contains all the information to describe a single
  229. requester.  It starts with a string that is to be the base name for this set
  230. of declarations.  There are then two optional numbers which are the default
  231. border color and default text color.  Neither need to be specified and will
  232. both default to 1.  Then comes the box definition followed by a set of
  233. extended gadget descriptions.  Some examples are included in this release.
  234.  
  235.  
  236. Using BLK:
  237.  
  238. The BLK commandline is:
  239.  
  240.    blk infile { "%" | outfile }
  241.  
  242. "Infile" is the input requester description.  The input file will be read
  243. and the resulting requester will be displayed in a window.  If no output is
  244. specified, BLK will wait for a few seconds and then exit.  (If you need more
  245. time to view the results of you handiwork, just hold down the right mouse
  246. button.)  If "%" is given as output, BLK will PRINT the box tree to standard
  247. output.  This can be a huge ammout of output, but can be useful if you need
  248. to know the exact coordinates or size of something.  If "outfile" is
  249. specified, BLK will output the C declarations to this file.
  250.  
  251. Stuart Ferguson
  252.             (shf@Solar.Stanford.EDU)    12/87
  253.             (shf@well.UUCP)
  254.